<!DOCTYPE html>

<html lang="en" data-content_root="../../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Compiling a tutorial from a Git repository &#8212; Pytch  documentation</title>
    <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=03e43079" />
    <link rel="stylesheet" type="text/css" href="../../_static/classic.css?v=36340f97" />
    <link rel="stylesheet" type="text/css" href="../../_static/css/pytch-classic.css?v=0321735e" />
    
    <script src="../../_static/documentation_options.js?v=7f41d439"></script>
    <script src="../../_static/doctools.js?v=9bcbadda"></script>
    <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="icon" href="../../_static/favicon.ico"/>
    <link rel="author" title="About these documents" href="../../about.html" />
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="Tutorial collection" href="tutorial-collection.html" />
    <link rel="prev" title="Tutorial structure" href="tutorial-structure.html" /> 
  </head><body>
<div class="NavBar">
  <a href="../../../app/"><h1>Pytch</h1></a>
  <ul>
    <a href="https://pytch.scss.tcd.ie/"><li>About Pytch</li></a>
    <a href="../../index.html"><li>Help</li></a>
    <a href="../../../app/tutorials/"><li>Tutorials</li></a>
    <a href="../../../app/my-projects/"><li>My projects</li></a>
  </ul>
</div>
<div class="warning-work-in-progress">
  <p>These help pages are incomplete — we are working on it!</p>
</div>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="compiling-a-tutorial-from-a-git-repository">
<h1>Compiling a tutorial from a Git repository<a class="headerlink" href="#compiling-a-tutorial-from-a-git-repository" title="Link to this heading">¶</a></h1>
<section id="structure-of-git-repo">
<h2>Structure of git repo<a class="headerlink" href="#structure-of-git-repo" title="Link to this heading">¶</a></h2>
<p>Each tutorial is in its own branch of the repo, and has its own
top-level directory within the repo.  We imagine such branches will
very often have their history re-written as we think of clearer ways
of structuring the development of the code.</p>
<p>The structure of the development of the code (its decomposition into
sections etc.) is provided by the <code class="docutils literal notranslate"><span class="pre">tutorial.md</span></code> document.</p>
<p>To identify particular commits touching the <code class="docutils literal notranslate"><span class="pre">code.py</span></code> file, the
author adds a <em>slug</em> to the commit message by starting the subject
with a string like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="c1">#fire-alien-missile}</span>
</pre></div>
</div>
<p>To refer to such a commit in the tutorial text, and bring in an
interactive patch element to the presentation, the author writes a
paragraph consisting of just a particular <em>shortcode</em> into the
<code class="docutils literal notranslate"><span class="pre">tutorial.md</span></code> file like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{{</span><span class="o">&lt;</span> <span class="n">commit</span> <span class="n">fire</span><span class="o">-</span><span class="n">alien</span><span class="o">-</span><span class="n">missile</span> <span class="o">&gt;</span><span class="p">}}</span>
</pre></div>
</div>
<p>(These shortcodes are modelled on Hugo’s.)</p>
</section>
<section id="creating-a-new-tutorial">
<span id="id1"></span><h2>Creating a new tutorial<a class="headerlink" href="#creating-a-new-tutorial" title="Link to this heading">¶</a></h2>
<p>There is an <strong>experimental</strong> tool for creating the necessary file and
repo structures for a new tutorial.  Within the <code class="docutils literal notranslate"><span class="pre">pytch-tutorials</span></code>
repo, and with the <code class="docutils literal notranslate"><span class="pre">pytchbuild</span></code> virtual environment activated, run
something like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pytchbuild</span><span class="o">-</span><span class="n">new</span><span class="o">-</span><span class="n">tutorial</span> \
  <span class="o">--</span><span class="n">tutorial</span><span class="o">-</span><span class="n">name</span><span class="o">=</span><span class="s2">&quot;Collect the diamonds&quot;</span> \
  <span class="o">--</span><span class="n">tutorial</span><span class="o">-</span><span class="n">branch</span><span class="o">=</span><span class="n">bn</span><span class="o">/</span><span class="n">collect</span><span class="o">-</span><span class="n">diamonds</span><span class="o">-</span><span class="mi">01</span> \
  <span class="o">--</span><span class="n">tutorial</span><span class="o">-</span><span class="n">slug</span><span class="o">=</span><span class="s2">&quot;collect-diamonds&quot;</span>
</pre></div>
</div>
<p>Where the three inputs give the short human-readable name, the branch
name to be created, and the name of the directory to be created.</p>
</section>
<section id="structure-of-tutorial-markdown-file">
<h2>Structure of tutorial markdown file<a class="headerlink" href="#structure-of-tutorial-markdown-file" title="Link to this heading">¶</a></h2>
<p>Consists of <em>front matter</em> followed by <em>chapters</em>.</p>
<section id="front-matter">
<h3>Front matter<a class="headerlink" href="#front-matter" title="Link to this heading">¶</a></h3>
<p>Start with level-1 heading naming the project.  Then whatever you
like, then a horizonal rule.  The rule marks the end of the front
matter and does not appear in the rendered tutorial.</p>
<p>Typically the rendered front matter will include a <em>try the project</em>
button, which is generated by the shortcode:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{{</span><span class="o">&lt;</span> <span class="n">run</span><span class="o">-</span><span class="n">finished</span><span class="o">-</span><span class="n">project</span> <span class="o">&gt;</span><span class="p">}}</span>
</pre></div>
</div>
<p>It will also typically include credits, including perhaps by use of the
shortcode:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{{</span><span class="o">&lt;</span> <span class="n">asset</span><span class="o">-</span><span class="n">credits</span> <span class="o">&gt;</span><span class="p">}}</span>
</pre></div>
</div>
<p>which brings in the credit information from the messages of commits
adding assets.</p>
</section>
<section id="chapters">
<h3>Chapters<a class="headerlink" href="#chapters" title="Link to this heading">¶</a></h3>
<p>After the horizontal rule, the markdown file should contain the
<em>chapters</em> of the tutorial.  Each chapter starts with a level-2
heading and continues until either the next level-2 heading or the end
of the file.  Within each chapter, level-3 or lower-level headings can
be used, as can any other markdown features.</p>
<section id="showing-patches">
<h4>Showing patches<a class="headerlink" href="#showing-patches" title="Link to this heading">¶</a></h4>
<p>At a point where the tutorial wants to show the exact change to the
code required to do the next step of the project, the author can write
a paragraph consisting of a <code class="docutils literal notranslate"><span class="pre">commit</span></code> shortcode:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{{</span><span class="o">&lt;</span> <span class="n">commit</span> <span class="n">fire</span><span class="o">-</span><span class="n">alien</span><span class="o">-</span><span class="n">missile</span> <span class="o">&gt;</span><span class="p">}}</span>
</pre></div>
</div>
<p>The compiler transforms this into a <code class="docutils literal notranslate"><span class="pre">&lt;div&gt;</span></code> with a particular
structure which can be picked up by the front end, to add
interactivity features.</p>
<p>(Currently the complete text of the <code class="docutils literal notranslate"><span class="pre">code.py</span></code> file as of that commit
is included as a data attribute.  This was used for an experimental
<em>make mine like this</em> feature, but currently is unused.  It bloats the
HTML fragment considerably.  Remove it?  Recover it from the sequence
of patches?)</p>
</section>
<section id="generating-commit-shortcodes-for-all-code-commits">
<h4>Generating commit shortcodes for all code commits<a class="headerlink" href="#generating-commit-shortcodes-for-all-code-commits" title="Link to this heading">¶</a></h4>
<p>The tool <code class="docutils literal notranslate"><span class="pre">pytchbuild-emit-commit-slugs-markdown</span></code> will emit, to
stdout, markdown text consisting of a sequence of <code class="docutils literal notranslate"><span class="pre">commit</span></code>
shortcodes, one per code commit in the history.  This can be copied
into the <code class="docutils literal notranslate"><span class="pre">tutorial.md</span></code> file as a basis for writing the tutorial
text.</p>
</section>
<section id="project-assets">
<h4>Project assets<a class="headerlink" href="#project-assets" title="Link to this heading">¶</a></h4>
<p>The project will require graphics and maybe sound assets.  These
files should be added in standard git commits.  More than one asset
can be added in a single commit, but such commits should <em>not</em> include
any other changes.</p>
<p>The commit message should include copyright and licence information,
for example creative commons, source attribution, etc.  This is
free-form markdown, and the text is gathered by the tutorial-compiler
and made available via the <code class="docutils literal notranslate"><span class="pre">asset-credits</span></code> shortcode.</p>
<p>Current thinking is that assets will be added and then left
unchanged.  Is there a use-case for modifying the graphics as part of
the tutorial?  If so, how to encode version information in the code?</p>
</section>
<section id="tutorial-assets">
<h4>Tutorial assets<a class="headerlink" href="#tutorial-assets" title="Link to this heading">¶</a></h4>
<p>Assets for use in the tutorial itself, for example screenshots, can be
included in a <code class="docutils literal notranslate"><span class="pre">tutorial-assets</span></code> directory.  Commits adding such
assets should have credits/licence information along the same lines as
the information given for project assets.</p>
</section>
</section>
</section>
<section id="tutorial-summary-file">
<h2>Tutorial summary file<a class="headerlink" href="#tutorial-summary-file" title="Link to this heading">¶</a></h2>
<p>The tutorial directory should also include a <code class="docutils literal notranslate"><span class="pre">summary.md</span></code> file at
top-level (so next to the <code class="docutils literal notranslate"><span class="pre">tutorial.md</span></code> file).  It should start with
a screenshot image, created along the lines of:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>![Screenshot](summary-screenshot.png)
</pre></div>
</div>
<p>and after that should have a H1 line, such as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Boing — a Pong-like game</span>
</pre></div>
</div>
<p>and after that is free-form, but should be kept fairly short.  One
paragraph of a few lines is enough.</p>
</section>
<section id="output-from-compiler">
<h2>Output from compiler<a class="headerlink" href="#output-from-compiler" title="Link to this heading">¶</a></h2>
<p>Zipfile containing a single directory at top level, whose name is
taken from the sole directoy at top-level in the repo (as of the tip
of the branch containing that particular tutorial).  Within that
directory, the contents are:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">tutorial.html</span></code> — HTML fragment suitable for loading by
interactive tutorial mechanism in webapp.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">project-assets/</span></code> — Directory containing images and/or sounds as
required by project which the tutorial explains.  Within the
tutorial Python, the URL is taken to refer to an object under
<code class="docutils literal notranslate"><span class="pre">project-assets/</span></code>.</p></li>
</ul>
<p>TODO: This information is independent of the fact that the zipfile
came from a git repo.  Move it to the general
<code class="docutils literal notranslate"><span class="pre">tutorial-structure.rst</span></code> file?</p>
</section>
<section id="internals">
<h2>Internals<a class="headerlink" href="#internals" title="Link to this heading">¶</a></h2>
<p>The following is cut/paste from an earlier version of the tool and
needs revising:</p>
<p>We collect the tutorial into chapters; each chapter is a list of
elements.  An ‘interactive patch’ element gets turned into a DIV with
the relevant patch as a table, as well as extra metadata.  Each
chapter starts with an H2 and continues until either the next H2 or
the end of the whole document.</p>
</section>
<section id="outline-design">
<h2>Outline design<a class="headerlink" href="#outline-design" title="Link to this heading">¶</a></h2>
<p>Major pieces are:</p>
<dl class="py class">
<dt class="sig sig-object py" id="Asset">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">Asset</span></span><a class="headerlink" href="#Asset" title="Link to this definition">¶</a></dt>
<dd><p>Graphics or sound asset belonging to project</p>
<p>Distinction is (or will be) against <em>tutorial</em> asset, e.g., a
screenshot to be included in the presentation.</p>
<p>Contains path (QN: relative to what?) and data-bytes.  Relative to
git root?</p>
</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="ProjectCommit">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">ProjectCommit</span></span><a class="headerlink" href="#ProjectCommit" title="Link to this definition">¶</a></dt>
<dd><p>Individual commit from history</p>
<p>Construct from repo and commit-OID.</p>
<p>Different types of commit:</p>
<ul class="simple">
<li><p>Identified commit belonging to project being developed: Expect
this to be used in tutorial.</p></li>
<li><p>Addition of asset/s: E.g., adding a graphics file.</p></li>
<li><p>The unique base commit: How much code should there be in this?
Just the <code class="docutils literal notranslate"><span class="pre">import</span></code> stuff at the top?</p></li>
<li><p>Updates just to the raw markdown of the tutorial text: Ignored
when generating tutorial.</p></li>
<li><p>TODO: Addition of tutorial assets, e.g., screenshots.</p></li>
</ul>
<dl class="py attribute">
<dt class="sig sig-object py" id="ProjectCommit.added_assets">
<span class="sig-name descname"><span class="pre">added_assets</span></span><a class="headerlink" href="#ProjectCommit.added_assets" title="Link to this definition">¶</a></dt>
<dd><p>A list of <a class="reference internal" href="#Asset" title="Asset"><code class="xref py py-class docutils literal notranslate"><span class="pre">Asset</span></code></a> instances.</p>
<p>QN: A given ProjectCommit might add more than one asset.  We
also have an explicit (but possibly redundant) tag in the
commit message to flag a commit as adding assets.  What if the
tag and the actual commit disagree?  Should it be possible to
do <a class="reference internal" href="#ProjectCommit.added_assets" title="ProjectCommit.added_assets"><code class="xref py py-attr docutils literal notranslate"><span class="pre">added_assets</span></code></a> on any <a class="reference internal" href="#ProjectCommit" title="ProjectCommit"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProjectCommit</span></code></a>?
Should this return an empty list if there are no added assets?
Emit a warning if it adds assets but doesn’t include the
<code class="docutils literal notranslate"><span class="pre">add-project-assets</span></code> tag (or vice versa)?  TODO: That tag is
no longer used I think?</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="ProjectCommit.maybe_identifying_slug">
<span class="sig-name descname"><span class="pre">maybe_identifying_slug</span></span><a class="headerlink" href="#ProjectCommit.maybe_identifying_slug" title="Link to this definition">¶</a></dt>
<dd><p>The text of the identifying slug, if one present, otherwise None.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">is_base:</span> <span class="pre">bool</span></span></dt>
<dd><p>Whether the commit message contains the magic ‘this is the base’ tag.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="ProjectCommit.modified_tutorial_text">
<span class="sig-name descname"><span class="pre">modified_tutorial_text</span></span><a class="headerlink" href="#ProjectCommit.modified_tutorial_text" title="Link to this definition">¶</a></dt>
<dd><p>Whether the commit updates just the
<code class="samp docutils literal notranslate"><em><span class="pre">TOP-LEVEL-DIRECTORY</span></em><span class="pre">/tutorial.md</span></code> file, and is not
otherwise tagged.</p>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="ProjectHistory">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">ProjectHistory</span></span><a class="headerlink" href="#ProjectHistory" title="Link to this definition">¶</a></dt>
<dd><p>Chain of git commits developing project from scratch.</p>
<p>Read in repo, starting at some commit and tracing back through
first parent until a given end commit.  Really just a list of
<cite>ProjectCommit</cite> objects.</p>
<p>Ctor inputs:</p>
<ul class="simple">
<li><p>Repo directory.  Branch name with latest commit in history to
process.  (QN: Might one day want to support more than one
‘final’ branch, to support ‘now you try this’, or ‘alternatively
we could have implemented this feature like this.)</p></li>
<li><p>Tip revision.</p></li>
<li><p>Which source to use for the tutorial text.</p></li>
</ul>
</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="TutorialRawText">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">TutorialRawText</span></span><a class="headerlink" href="#TutorialRawText" title="Link to this definition">¶</a></dt>
<dd><p>Document with tutorial text and DIVs for rich content</p>
<p>Read in tutorial text, break down into sections, identify pieces
where augmentation from the git repo is required.</p>
<p>Ctor inputs:</p>
<ul class="simple">
<li><p>Filename of markdown file.</p></li>
</ul>
<p>Representation:</p>
<p>Soup?  Whose job is it to manipulate the soup to add the
attributes etc. to the DIVs for interactive commits?  And who owns
the soup?  Probably OK for it to live in the TutorialRawText, but
for the convention to be that when that TutorialRawText is handed
over to the TutorialBundle ctor, the contained soup is available
for the TutorialBundle to mutate.</p>
</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="TutorialBundle">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">TutorialBundle</span></span><a class="headerlink" href="#TutorialBundle" title="Link to this definition">¶</a></dt>
<dd><p>Filesystem fragment (tutorial.html, assets/ directory)</p>
<p>Representation of everything needed to emit the tutorial bundle:</p>
<ul class="simple">
<li><p>Raw text (<cite>TutorialRawText</cite>)</p></li>
<li><p>Git repo / project history (<a class="reference internal" href="#ProjectHistory" title="ProjectHistory"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProjectHistory</span></code></a>)</p></li>
</ul>
<p>Constructed from the above two things.</p>
<dl class="py method">
<dt class="sig sig-object py" id="TutorialBundle.write_new_zipfile">
<span class="sig-name descname"><span class="pre">write_new_zipfile</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">file_or_filename</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#TutorialBundle.write_new_zipfile" title="Link to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="TutorialBundle.write_to_zipfile">
<span class="sig-name descname"><span class="pre">write_to_zipfile</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">existing_open_zipfile</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#TutorialBundle.write_to_zipfile" title="Link to this definition">¶</a></dt>
<dd></dd></dl>

</dd></dl>

</section>
<section id="todos">
<h2>TODOs<a class="headerlink" href="#todos" title="Link to this heading">¶</a></h2>
<p>Validation and/or warnings would be nice, including:</p>
<ul class="simple">
<li><p>each project asset has a path within the ‘project-assets/’ directory</p></li>
<li><p>exactly those commits tagged as adding project assets do in fact add project assets</p></li>
<li><p>all changes to the code file are tagged with identifier-slugs</p></li>
<li><p>all untagged commits are changes to the tutorial.md file</p></li>
<li><p>there is exactly one base in the history</p></li>
<li><p>the history has no merges</p></li>
</ul>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../webapp/user/index.html">Using the Pytch web app</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../vm/user/index.html">Writing Pytch programs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../about.html">About Pytch</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../developer.html">Developer documentation</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../developer/development-setup.html">Development setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/design-overview.html">Design overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../vm/developer/index.html">VM</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../webapp/developer/index.html">Webapp</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../medialib/developer/index.html">Media library</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/index.html">Website</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Tools</a><ul class="current">
<li class="toctree-l3 current"><a class="reference internal" href="../index.html#tutorial-compiler-and-related-tools">Tutorial compiler and related tools</a></li>
<li class="toctree-l3"><a class="reference internal" href="../index.html#assembly-of-website-bundle">Assembly of website bundle</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../source-build.html">Source and build information</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../releases/changelog.html">Changelog</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../legal/index.html">Legal information</a></li>
</ul>
<div class="docs-home-link"><hr>
  <ul>
    <li>
      <a href="../../index.html">Pytch help home</a>
    <li>
  </ul>
</div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
  </body>
</html>